home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / qbbs / qkecc100.zip / QKECC100.DOC < prev    next >
Text File  |  1990-11-28  |  17KB  |  414 lines
  1. QKECC: QuickBBS Embedded Code Compiler - Version 1.00
  2. Copyright (C) 1990 by David B. Thompson; All Rights Reserved.
  3.  
  4.  
  5. WHAT IS IT?
  6. -----------
  7.  
  8. QKECC and QKECU are a pair of programs for creating and maintaining text
  9. files used to run a QuickBBS bulletin board system.  QKECC "compiles" QBBS 
  10. embedded codes (used to display system and user information) and ANSI color 
  11. and screen control codes from keywords (listed below).  The resulting files 
  12. may be used as menus (using an auto-executed type 40 command) or simply 
  13. displayed as text files containing user or system information (using a type 
  14. 5, 40 or 45 command).  QKECU reverses the process, that is, it produces a 
  15. file containing keywords translated from the embedded codes and ANSI escape 
  16. sequences, plus any text contained in the file.
  17.  
  18.  
  19. LICENSE:
  20. --------
  21.  
  22. This is a shareware program.  Sysops are welcome to use this program
  23. without compensation, but contributions not to exceed $5.00 are welcome.
  24. Let your conscience be your guide.  All monies will be used to support my
  25. BBS.  In any event, please distribute this program by sharing it through
  26. bulletin board systems or other means.
  27.  
  28. If you are a user residing outside the United States, please send me a
  29. postcard of your town or surrounding countryside.  I got this idea from
  30. Stig Jacobsen (author of FileDoor) and think it is really neat!  I'm sure
  31. my kids will appreciate cards from around the world <grin>!
  32.  
  33. Under no circumstances is the program to be distributed for a fee (this 
  34. includes public domain libraries that charge "copying costs" for software 
  35. distribution) without prior arrangements with the author.  Bulletin board 
  36. systems which charge a fee for normal access may distribute this program.  
  37. Similarly, no modified version of the program may be distributed.  Finally, 
  38. do not distribute the software under any name but QKECC???.(ZIP ARC LZH or
  39. whatever), that is, you may rearchive the software, but do not change the 
  40. name or version number. 
  41.  
  42.  
  43. DISCLAIMER:
  44. -----------
  45.  
  46. This program is warranted to do no more than take up space on your disk. In 
  47. using this program, you accept complete responsibility for anything that 
  48. happens to your system and agree to release me from any and all liability.  
  49. Every effort has been made to provide bug-free software, but there is no 
  50. warranty as to suitability, merchantability or functionality.  What do you
  51. expect for 0 to 5 dollars?
  52.  
  53.  
  54. PAYMENT:
  55. --------
  56.  
  57. Contributions for the software may be directed to:
  58.  
  59.                              David B. Thompson
  60.                                204 Brookdale
  61.                           Carriere, MS  39426  USA
  62.  
  63.  
  64. QKECC PROGRAM USE:
  65. ------------------
  66.  
  67. Use of QKECC is very simple.  At the command line, enter the following 
  68. command: 
  69.  
  70.                    QKECC Input.Qec Output.A?? /a /o
  71.  
  72. where:
  73.         Input.Qec  is the file containing QBBS and ANSI keywords.
  74.         Output.Qec is the file containing QBBS and/or ANSI control codes.
  75.         /a         is a switch that enables generation of ANSI codes.
  76.         /o         is a switch that enables automatic overwriting of
  77.                    and existing output file.
  78.  
  79. The file, input.qec, contains text and command keywords you provide.  The 
  80. file output.a?? contains your text, with QBBS embedded command codes and 
  81. ANSI color or screen control codes.  Maximum line length of the input and 
  82. output files is 255 characters.  The number of lines in the file is 
  83. unlimited.
  84.  
  85. The /a is a switch that turns on generation of ANSI color and screen
  86. control codes.  If you don't specify the ANSI switch, then ANSI keywords
  87. are ignored and are not placed in the output file.  In this case,
  88. straight ASCII text will be passed through, with the substitution of the
  89. QBBS control codes for appropriate keywords.  Note that you should not
  90. embed ANSI characters in a *.ASC file because QBBS sends *.ASC files to
  91. users who do not use ANSI.SYS.  Be forewarned, you'll get lots of grief
  92. from your users if you make this mistake!
  93.  
  94. The /o switch turns overwrite mode on.  Be careful, because the program
  95. won't ask you if it's acceptable to write over an existing output file.
  96. The purpose of this switch is to allow you to construct a make file for
  97. all your text files.
  98.  
  99.  
  100. If you don't enter the names on the command line, then you will prompted 
  101. for them.  If you should specify the same filename for both input and 
  102. output, you will be warned and program execution will cease. 
  103.  
  104. All commands are delineated by placing them in brackets '[' and ']'.  No 
  105. spaces are allowed between the brackets and the command text.  Unmatched 
  106. brackets are not filtered, but passed through the program as is. 
  107. Unrecognized commands are also passed through the program.  The program is 
  108. not case sensitive. 
  109.  
  110.  
  111. QKECU PROGRAM USE:
  112. ------------------
  113.  
  114. To decompile a text file, enter:
  115.  
  116.                    QKECU Input.a?? Output.Qec
  117.  
  118. The file, Output.Qec, will contain the QBBS keywords and ANSI keywords
  119. corresponding to the codes found in the input.a?? file.  You may modify
  120. the file and recompile the file using QKECC.
  121.  
  122.  
  123. WARNING:
  124. --------
  125.  
  126. Be careful when decompiling ASC files.  If you have an existing .QEC
  127. file which contains ANSI keywords and decompile a .ASC file and
  128. overwrite it, then your ANSI keywords will be lost!  You get a chance to
  129. abort an overwrite, but you should still be careful.  (A backup of your
  130. .QEC files is probably an *EXCELLENT* idea...)
  131.  
  132.  
  133. EXAMPLES:
  134. ---------
  135.  
  136. In the file MAIN.QEC, you will find my main menu file, uncompiled.  This
  137. file is provided to give you an example to follow.  You can (and should)
  138. play with this a little to give you a feel for how the compiler and
  139. decompiler work.
  140.  
  141. If you use a make utility for programming purposes, you can set up a
  142. dependency file for QKECC, and maintain your text files and menus very
  143. easily.  This is probably one of the most powerful ways to apply QKECC.
  144.  
  145.  
  146. COMMAND LIST (from QBBS version 2.64):
  147. --------------------------------------
  148.  
  149.  QBBS
  150. Command       Meaning
  151. -------       -------
  152.  
  153. PAUSE         Pause and wait for Enter.
  154. ABORTOFF      Turn 'S' aborts off.
  155. ABORTON       Turn 'S' aborts on.
  156. MOREON        Turn 'more' on.
  157. MOREOFF       Turn 'more' off.
  158. BELL          Ring the user's bell.
  159. CLS           Clear the screen.
  160. USERNAME      Display full user name.
  161. CITYSTAT      Display user's city and state.
  162. PASSWORD      Display user's password.
  163. BUSPHONE      Display user's business/data phone number.
  164. HOMPHONE      Display usre's home/voice phone number.
  165. LASTDATE      User's last logon date.
  166. LASTTIME      User's last logon time.
  167. AFLAGS        Display user's A flags.
  168. BFLAGS        Display user's B flags.
  169. CFLAGS        Display user's C flags.
  170. DFLAGS        Display user's D flags.
  171. CREDIT        Display user's net mail credit.
  172. POSTS         User's number of message posts.
  173. MESSREAD      Display user's high read message.
  174. SECLVL        Display user's security level.
  175. LOGONS        User's number of times logged on.
  176. UPLOADS       User's number of uploads.
  177. UPLDK         User's uploads in Kbytes.
  178. DNLOADS       User's number of downloads.
  179. DNLDK         User's downloads in Kbytes.
  180. ELAPTIME      Display time used this call.
  181. SCNLGTH       Display user's screen length.
  182. FNAME         User's first name.
  183. ANSI          Show the state of the ANSI graphics toggle.
  184. MORE          Show the state of the more toggle.
  185. SCNCLR        Show the state of the screen clear codes toggle.
  186. FSEDIT        Show the state of the full screen editor toggle.
  187. CALLS         Display number of calls on the system.
  188. LASTCALL      Display last caller's name.
  189. ACTMESS       Show number of active messages.
  190. LOWMESS       Display low message number.
  191. HIGHMESS      Display high message number.
  192. PAGES         Display the number of sysop pages the user has made.
  193. FULLDOW       Show the full day-of-week.
  194. NOUSERS       Display the total number of users.
  195. TIME24        Display current time in 24hr format.
  196. DATE          Display current date.
  197. CONMIN        Show user's minutes of connect time.
  198. CONSEC        Show user's seconds of connect time (fractional minutes).
  199. MINUSED       Display user's number of minutes used.
  200. SECUSED       Display user's number of seconds used.
  201. MINREM        Show user's remaining minutes.
  202. SECREM        Show user's remaining seconds.
  203. TIMELIM       Show user's time daily time limit.
  204. BAUD          Display user's current baud rate.
  205. ABDOW         Display abbreviated day-of-week.
  206. DNLIMIT       Show user's download limit (for the day).
  207. TILEVENT      Display number of minutes until the next system event.
  208. TIMEVENT      Display the time of the next system event.
  209. TERMINAT      End current call.
  210.  
  211.  
  212.  ANSI
  213. Command       Meaning
  214. -------       -------
  215.  
  216. CLRSCN        Clear the screen.
  217. SAVECSR       Save the cursor position.
  218. RESTCSR       Restore the cursor postion.
  219. UP(x)         Move the cursor up x rows.
  220. DOWN(x)       Move the cursor down x rows.
  221. RIGHT(x)      Move the cursor right x columns.
  222. LEFT(x)       Move the cursor left x columns.
  223. HOME          Send the cursor home to 1,1.
  224. BLINK         Make subsequent text blink.
  225. REVERSE       Make subsequent text reverse video (dark on light).
  226. NORMAL        Make subsequent text normal video.
  227. GOTOXY(x,y)   Send the cursor to row x and column y.
  228. CLREOL        Clear to end of line.
  229. HIGH          Makes the following color "bright."
  230. RESET         Restores the normal grey on black colors of DOS.
  231. RED           Red foreground.
  232. YELLOW        Yellow foreground.
  233. MAGENTA       Magenta foreground.
  234. WHITE         White foreground.
  235. BLACK         Black foreground.
  236. GREEN         Green foreground.
  237. BLUE          Blue foreground.
  238. CYAN          Cyan foreground.
  239. REDBK         Red background.
  240. YELLOWBK      Yellow background.
  241. MAGENTBK      Magenta background.
  242. WHITEBK       White background.
  243. BLACKBK       Black background.
  244. GREENBK       Green background.
  245. BLUEBK        Blue background.
  246. CYANBK        Cyan background.
  247.  
  248.  Other
  249. Command       Meaning
  250. -------       -------
  251.  
  252. INCLUDE       Include the contents of the file defined by the filename
  253.               immediately following the INCLUDE command.  Succeeding
  254.               text (if any) in the original file is appended to that from
  255.               the include file (if any).  In-line includes are
  256.               supported.  Nested includes are not supported.
  257.  
  258. Example:
  259.  
  260. [INCLUDE  C:\TEXT\SECLEVEL.INC ] would cause the file seclevel.inc to be
  261. included in the output file.  If the file doesn't exist, then the INCLUDE
  262. command is ignored.
  263.  
  264.  
  265. ERRORS
  266. ------
  267.  
  268. Erroneous embedded or ANSI codes are ignored.  To facilitate debugging, the
  269. code in error is left embedded in the output stream.  A quick scan of the
  270. output file should allow you to find any errors.  If an include file is not
  271. found, then the include command is ignored.
  272.  
  273. As of version 0.33, THEDRAW screens can be decompiled by QKECU.  However,
  274. before they can be recompiled using QKECC, some hand tuning will be
  275. required.  This occurs because THEDRAW fills each line (255 bytes) with
  276. codes.  The decompiled codes then exceed 255 bytes because the keywords are
  277. longer than the codes they represent.  So, I was forced to include an CR/LF
  278. combination to keep line lengths under 255 bytes.  Sorry about this, and
  279. I'll fix it if I can.
  280.  
  281.  
  282. CREDITS:
  283. --------
  284.  
  285. QuickBBS is copyrighted by Adam Hudson.
  286.  
  287. This program is written in Turbo Pascal 5.5, a trademark of Borland
  288. International.
  289.  
  290. The idea for this program came from two sources: OECC, the OPUS embedded
  291. command compiler, and QECC, the QuickBBS Embedded Code Compiler produced
  292. by Dave Kerley of Turbo-Soft.
  293.  
  294. I appreciate the efforts of the beta testers: Mark Howard (Rivendell) and 
  295. Steve Gabrilowitz (aka Captain Kirk of NCC-1701).  Mark Howard suggested 
  296. the idea of the code decompiler.  Bill Kraski also had a hand in the
  297. beta testing of this program.
  298.  
  299.  
  300. BUG REPORTS:
  301. ------------
  302.  
  303. If you find a bug, send me netmail at 1:390/2.1 or write to me at the
  304. above address.
  305.  
  306. Please be sure to include as complete a description of the circumstances
  307. as you can.  A description of your hardware/software configuration will
  308. also be helpful.  Please include the error number and address, i.e.,
  309. RunTime Error ??? at 0000:0000 (you fill in the numbers!), if
  310. appropriate.  I prefer to receive a file containing the text on which the
  311. program bombed so I can reproduce the problem.
  312.  
  313.  
  314. COMMENTS ON MENU DESIGN:
  315. ------------------------
  316.  
  317. When designing screens, I suggest you start out with a mockup.  Use a
  318. text editor (such as QEdit) to do all the layout of your screens, put in
  319. boxes, draw pictures of the menu trees, and so forth.  You should tinker
  320. with these text files until you have a good idea of how you want your
  321. screens to look.
  322.  
  323. Then, WITH A COPY of your basic layout, insert the keywords for colors
  324. and QBBS commands.  You can use QKECC to compile the screens and then
  325. TYPE them to see how they will look.  For ANSI screens, be sure you have
  326. ANSI.SYS, or one of the excellent replacements, loaded in your config.sys
  327. file.  When you get close to your goal, fire up your menu editor and
  328. create the control portion of your menus.  Fire up QBBS and take a look
  329. at your results.
  330.  
  331. Be sure to retain your original mockup.  If you don't like the results
  332. of your work, you can go back and modify your original ideas until you
  333. get a set of screens that satisfy you.  Expect to make several trials
  334. before arriving at a finished product.
  335.  
  336. There are a couple of principles you should follow.  First, never leave
  337. the user without a way to the top (or main) menu.  With complicated menu
  338. topologies, it is very easy to lose your way and get frustrated.  If
  339. this happens, your will get a lot of hangups and few frequent callers.
  340.  
  341. Second, show the user the path they used to get to the current menu.  I
  342. use names and arrows to indicate the path at the top left of my screens.
  343. I've seen some very nice trees on a couple of boards; you could use
  344. these too.
  345.  
  346. Third, grouping is important.  Use location to group related commands.
  347. On my main menu (see the example), I've grouped the file, system and
  348. mail commands into thirds of the screen.  That way, the user can find
  349. the command they want and execute it without hunting all over the
  350. screen.
  351.  
  352. Fourth, use mnemonic keys whenever possible.  This aids remembering the
  353. commands and helps limit the amount of time required to execute the
  354. desired function.  The hot keys concept of QBBS is very attractive (it
  355. is one of my favorite features) because it supports the power user.
  356.  
  357. Fifth, use color to delineate your menus for color callers.  With care,
  358. you can also support your monochrome callers because some colors are
  359. rendered as high intensity on mono screens.
  360.  
  361. It takes some fine tuning the get a menu structure that you like
  362. (believe me, expect to spend some time at it).  With the general
  363. guidelines above, you should be able to construct some fine menus if you
  364. apply yourself.
  365.  
  366.  
  367. QUESTIONS AND COMMENTS:
  368. -----------------------
  369.  
  370. Send your comments, suggestions and compliments to me at the ground
  371. address above or via Fidonet at node 1:390/2.1.  Save us both time and
  372. aggravation by sending your complaints to NUL.
  373.  
  374.  
  375. HISTORY:
  376. --------
  377.  
  378.  6/30/89 - Version 0.10.  This was the original beta version.  Just a Plain
  379.            Jane keyword compiler.
  380.  
  381.  7/09/89 - Version 0.21.  This beta included ANSI screen control and color
  382.            codes.  It also included a decompiler which created keywords from
  383.            the control codes and ANSI escape sequences produced by the compiler.
  384.  
  385.  9/03/89 - Version 0.30.  This beta eliminated the need for both ANSI and
  386.            ASCII versions of text files to be maintained because the /a
  387.            paramter was added to allow generation of ANSI codes.  The
  388.            include command was implemented and the new QBBS 2.04 terminate
  389.            call embedded command was supported.
  390.  
  391.  9/04/89 - Version 0.31.  This beta added code to put the input and output
  392.            file names on the screen.  I found this helpful when using MAKE
  393.            to compile my text screens.
  394.  
  395.  9/23/89 - Version 0.32.  This beta killed a bug in the include file
  396.            routine, added code to allow in-line includes, added the /o
  397.            overwrite switch and some general clean-up of the code.
  398.  
  399. 10/01/89 - Version 0.33.  This beta patched a bug in the decompiler which
  400.            caused the compiler to die when recompiling certain files.  The
  401.            bug no longer occurs, but the compiled screens still aren't
  402.            quite right.  Please see the text.  Also, the TERMINAT current
  403.            call command was added to the decompiler.  Somehow, this command
  404.            was overlooked in earlier versions.  This is the first
  405.            general release.
  406.  
  407. 04/15/90 - Version 0.36.  All RA support has been removed because a separate
  408.            product has been generated for that software.  Also, support for
  409.            the full screen editor command has been added.
  410.  
  411. 11/28/90 - Version 1.00.  Fixed a bug in the CLREOL output.  The code was
  412.            generating an ESC[k instead of the correct ESC[K.
  413.  
  414.